/*
 * Copyright (C) 2010-2011 Comcast Cable.  All Rights Reserved.
 */
package com.hercules.android.receiver.factories;

import android.content.Context;

import com.hercules.android.receiver.AndroidReceiver;
import com.hercules.android.receiver.AndroidReceiverErrorHandler;
import com.hercules.android.receiver.connection.ServerConnection;
import com.hercules.android.receiver.handlers.commands.XREAggregateCommandHandler;

/**
 * This interface defines the contract for creating various classes needed by the {@link AndroidReceiver}.
 * Implementations must have constructor that will accept {@link Context} parameter.
 * <p>
 * AndroidAssembly1 added requirement for {@link Context} constructor
 * <p>
 * <b>Thread Safety:</b> Implementations are expected to be effectively thread-safe.
 *
 * @author argolite, 7realm
 * @author 7realm
 * @version 1.0
 */
public interface AndroidReceiverFactory {
    /**
     * Creates an instance of the {@link ServerConnection} using the given key.
     *
     * @param key a key indicating the ServerConnection to create
     * @return the {@link ServerConnection} instance
     * @throws IllegalArgumentException if key is empty/null
     * @throws AndroidReceiverFactoryException if there is an error while creating the instance or key is not recognized
     */
    ServerConnection createServerConnection(String key) throws AndroidReceiverFactoryException;

    /**
     * Creates an instance of the {@link XREAggregateCommandHandler} using the given key.
     *
     * @param key a key indicating the {@link XREAggregateCommandHandler} to create
     * @return the {@link XREAggregateCommandHandler} instance
     * @throws IllegalArgumentException if key is empty/null
     * @throws AndroidReceiverFactoryException if there is an error while creating the instance or key is not recognized
     */
    XREAggregateCommandHandler createXREAggregateCommandHandler(String key) throws AndroidReceiverFactoryException;

    /**
     * Creates an instance of the {@link AndroidReceiverErrorHandler} using the given key.
     *
     * @param key a key indicating the {@link AndroidReceiverErrorHandler} to create
     * @return the {@link AndroidReceiverErrorHandler} instance
     * @throws IllegalArgumentException if key is empty/null
     * @throws AndroidReceiverFactoryException if there is an error while creating the instance or key is not recognized
     */
    AndroidReceiverErrorHandler createErrorHandler(String key) throws AndroidReceiverFactoryException;
}